/*
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 */
package erwiki.api.render;

import java.io.IOException;

import org.elwiki_data.WikiPage;

import erwiki.LinkCollector;
import erwiki.api.modules.InternalModule;
import erwiki.api.parser.MarkupParser;
import erwiki.api.parser.WikiDocument;

/**
 * This class provides a facade towards the differing rendering routines. You should use the
 * routines in this manager instead of the ones in Engine, if you don't want the different side
 * effects to occur - such as WikiFilters.
 * <p>
 * This class also manages a rendering cache, i.e. documents are stored between calls. You may
 * control the cache by tweaking the ehcache.xml file.
 * <p>
 *
 * @since 2.4
 */
public interface RenderingManager extends InternalModule {

	/** markup parser property. */
	String PROP_PARSER = "jspwiki.renderingManager.markupParser";

	/** default renderer property. */
	String PROP_RENDERER = "jspwiki.renderingManager.renderer";

	/** default wysiwyg renderer property. */
	String PROP_WYSIWYG_RENDERER = "jspwiki.renderingManager.renderer.wysiwyg";

	/** Name of the regular page cache. */
	String DOCUMENTCACHE_NAME = "jspwiki.renderingCache";

	/**
	 * Returns the wiki Parser
	 *
	 * @param pagedata the page data
	 * @return A MarkupParser instance.
	 */
	MarkupParser getParser(String pagedata);

	/**
	 * Returns a cached document, if one is found.
	 *
	 * @param pagedata the page data
	 *
	 * @return the rendered wiki document
	 */
	WikiDocument getRenderedDocument(String pagedata);

	/**
	 * Returns a WikiRenderer instance, initialized with the given context and doc. The object is an
	 * XHTMLRenderer, unless overridden in preferences.ini with PROP_RENDERER.
	 *
	 * @param doc The document to render
	 *
	 * @return A WikiRenderer for this document, or null, if no such renderer could be instantiated.
	 */
	WikiRenderer getRenderer(WikiDocument doc);

	/**
	 * Returns a WikiRenderer instance meant for WYSIWYG editing, initialized with the given context and
	 * doc. The object is an WysiwygEditingRenderer, unless overridden in preferences.ini with
	 * PROP_WYSIWYG_RENDERER.
	 *
	 * @param doc The document to render
	 *
	 * @return A WikiRenderer instance meant for WYSIWYG editing, for this document, or null, if no such
	 *         renderer could be instantiated.
	 */
	WikiRenderer getWysiwygRenderer(WikiDocument doc);

	/**
	 * Simply renders a WikiDocument to a String. This version does not get the document from the cache
	 * - in fact, it does not cache the document at all. This is very useful, if you have something that
	 * you want to render outside the caching routines. Because the cache is based on full pages, and
	 * the cache keys are based on names, use this routine if you're rendering anything for yourself.
	 *
	 * @param doc A proper WikiDocument
	 *
	 * @return Rendered HTML.
	 * @throws IOException If the WikiDocument is poorly formed.
	 */
	String getHTML(WikiDocument doc) throws IOException;

	/**
	 * Возвращает HTML-код содержимого страницы, используя различные RWC контексты.</br>
	 * После содержимого страницы, комментарии страницы добавляются через разделители.
	 *
	 * @param page WikiPage reference.
	 *
	 * @return HTML-rendered version of the page.
	 */
	String getHTML(WikiPage page);

	/**
	 * Returns the converted HTML of the page's specific version. The version must be a positive
	 * integer, otherwise the current version is returned.
	 *
	 * @param wikiPage WikiName of the page to convert.
	 * @param version  Version number to fetch
	 * @return HTML-rendered page text.
	 */
	String getHTML(WikiPage wikiPage, int... version);

	/**
	 * Преобразует необработанные (raw) данные содержимого страницы в HTML.
	 *
	 * @param pagedata Raw данные страницы для преобразования в HTML.
	 *
	 * @return Подготовленный в HTML текст страницы.
	 */
	String textToHTML(String pagedata);

	/**
	 * Вспомогательный метод для трансляции HTML.
	 *
	 * @param pagedata           Данные для рендеринга.
	 * @param localLinkCollector Вызывается всякий раз, когда находится вики-ссылка.
	 * @param extLinkCollector   Вызывается всякий раз, когда обнаруживается внешняя ссылка
	 * @param attLinkCollector   Вызывается всякий раз, когда...
	 * @param parseAccessRules   Указывает: разбирать/нет правила доступа, если встретятся.
	 * @param justParse          =true: указывает просто анализировать данные страницы, и не выполнять
	 *                           рендеринг. В таком случае метод возвратит пустую строку.
	 * @return Текст страницы, отображаемый в формате HTML.
	 */
	String textToHTML(String pagedata, LinkCollector localLinkCollector, LinkCollector extLinkCollector,
			LinkCollector attLinkCollector, LinkCollector unknownPagesLinkCollector, boolean parseAccessRules,
			boolean justParse);

	/**
	 * Just convert WikiText to HTML.
	 *
	 * @param pagedata           The data to render
	 * @param localLinkCollector Is called whenever a wiki link is found
	 * @param extLinkCollector   Is called whenever an external link is found
	 *
	 * @return HTML-rendered page text.
	 */
	default String textToHTML(final String pagedata, final LinkCollector localLinkCollector,
			final LinkCollector extLinkCollector) {
		return textToHTML(pagedata, localLinkCollector, extLinkCollector, null, null, true, false);
	}

	/**
	 * Just convert WikiText to HTML.
	 *
	 * @param pagedata           The data to render
	 * @param localLinkCollector Is called whenever a wiki link is found
	 * @param extLinkCollector   Is called whenever an external link is found
	 * @param attLinkCollector   Is called whenever an attachment link is found
	 *
	 * @return HTML-rendered page text.
	 */
	default String textToHTML(final String pagedata, final LinkCollector localLinkCollector,
			final LinkCollector extLinkCollector, final LinkCollector attLinkCollector) {
		return textToHTML(pagedata, localLinkCollector, extLinkCollector, attLinkCollector, null, true, false);
	}

}
